{
"cells": [
{
"cell_type": "markdown",
"id": "05d1beeb",
"metadata": {},
"source": [
"# MusicBox Basic Workflow Tutorial\n",
"\n",
"Hello, and welcome to the MusicBox basic workflow tutorial! Here, we will be covering some basic usages of the MusicBox library."
]
},
{
"cell_type": "markdown",
"id": "c752b1cd",
"metadata": {},
"source": [
"## What is MusicBox?\n",
"\n",
"MusicBox is a library with a Python API for box modeling that builds on top of musica, a collection of modeling software that allows for robust modeling of chemistry in Earth's atmosphere.\n",
"\n",
"Boxes refer to a set of adjacent grid cells that represent the exchange of information."
]
},
{
"cell_type": "markdown",
"id": "59167a93",
"metadata": {},
"source": [
"## 1. Creating a Conda Environment (Optional)\n",
"\n",
"Before getting started, make sure your Python version is 3.10 or higher. You can optionally set up a conda environment. If you prefer to use an existing Python 3.10+ environment, you can skip to step 2.\n",
"\n",
"To create a new conda environment, execute these commands in your terminal:\n",
"\n",
"```\n",
"conda create --name music_box python=3.13\n",
"conda activate music_box\n",
"```"
]
},
{
"cell_type": "markdown",
"id": "5ccc7e1b",
"metadata": {},
"source": [
"## 2. Downloading MusicBox\n",
"\n",
"To install MusicBox onto your device, run this tutorial\n",
"\n",
"```\n",
"pip install acom_music_box[tutorial] #bash\n",
"pip install 'acom_music_box[tutorial]' #zsh\n",
"```\n",
"\n",
"Note: Installing MusicBox will automatically install musica, a required dependency of MusicBox that is used throughout this tutorial."
]
},
{
"cell_type": "markdown",
"id": "f20cd18a",
"metadata": {},
"source": [
"## 3. Importing MusicBox\n",
"\n",
"To import your newly-downloaded MusicBox into a Python file, as well as some other libraries so that this demo can run:"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "fd1b5247",
"metadata": {},
"outputs": [],
"source": [
"from acom_music_box import MusicBox\n",
"import musica.mechanism_configuration as mc\n",
"import matplotlib.pyplot as plt"
]
},
{
"cell_type": "markdown",
"id": "f2488c7c",
"metadata": {},
"source": [
"This code cell may take upwards of 2 minutes to run on the first execution depending on your system, so do not fret if it feels a bit sluggish at first."
]
},
{
"cell_type": "markdown",
"id": "1ec851da",
"metadata": {},
"source": [
"## 4. Defining a System\n",
"\n",
"In MusicBox, a system is defined by a mechanism that includes:\n",
"* a set of species and their respective phases, and\n",
"* a set of reactions that the species participate in.\n",
"\n",
"The system is the fundamental building block of MusicBox and is your main concern when using this library.\n",
"\n",
"The following steps will walk you through:\n",
"* creating your own system,\n",
"* solving your system, and\n",
"* viewing and visualizing your results."
]
},
{
"cell_type": "markdown",
"id": "ab84f835",
"metadata": {},
"source": [
"### 4a. Defining Species\n",
"\n",
"A species is simply a reactant or product in a chemical reaction.\n",
"\n",
"You have the freedom to name a species anything in MusicBox, just make sure that it is logical to you.\n",
"\n",
"For extended documentation about the Species class, go [here](https://ncar-musica.readthedocs.io/en/latest/api/python.html#musica.mechanism_configuration.Species).\n",
"\n",
"Here is a snippet that defines three chemical species:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "654b7e30",
"metadata": {},
"outputs": [],
"source": [
"# Create each of the species that will be simulated and gas phase\n",
"X = mc.Species(name=\"X\")\n",
"Y = mc.Species(name=\"Y\")\n",
"Z = mc.Species(name=\"Z\")\n",
"species = {\"X\": X, \"Y\": Y, \"Z\": Z}\n",
"gas = mc.Phase(name=\"gas\", species=list(species.values()))"
]
},
{
"cell_type": "markdown",
"id": "9e6190b7",
"metadata": {},
"source": [
"This code block creates 3 species called X, Y, and Z and adds them to a dictionary called species.\n",
"\n",
"The variable name and the name of the species are not required to be the same, but it is strongly recommended so that your code is more organized.\n",
"\n",
"Next, a phase is created named \"gas\". In MusicBox, phases are essentially collections of species that are assumed to be well-mixed.\n",
"\n",
"**Note:** Creating the species dictionary and the phase is mandatory, as subsequent code relies on the data being bundled in specific object types."
]
},
{
"cell_type": "markdown",
"id": "1afce428",
"metadata": {},
"source": [
"### 4b. Defining Reactions\n",
"\n",
"A chemical reaction is a process in which a set of reactants transforms into a set of products.\n",
"\n",
"To define a reaction in MusicBox:"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "bf790275",
"metadata": {},
"outputs": [],
"source": [
"# Define the Arrhenius reactions\n",
"arr1 = mc.Arrhenius(name=\"X->Y\", A=4.0e-3, C=50, reactants=[species[\"X\"]], products=[species[\"Y\"]], gas_phase=gas)\n",
"arr2 = mc.Arrhenius(name=\"Y->Z\", A=4.0e-3, C=50, reactants=[species[\"Y\"]], products=[species[\"Z\"]], gas_phase=gas)\n",
"rxns = {\"X->Y\": arr1, \"Y->Z\": arr2}"
]
},
{
"cell_type": "markdown",
"id": "00cb442b",
"metadata": {},
"source": [
"This code block uses the gas and species variables from the previous code block.\n",
"\n",
"Using the species and gas variables, it creates two reactions: arr1 and arr2.\n",
"\n",
"The arr1 variable represents the conversion of X (reactant) into Y (product) and defines Arrhenius rate constant parameters:\n",
"* **A**: Pre-exponential factor (4.0e-3 in this example)\n",
"* **C**: Temperature coefficient (50 in this example)\n",
"\n",
"The arr2 variable is just like arr1, but instead it represents the conversion of Y (reactant) into Z (product).\n",
"\n",
"These reactions are then bundled into a dictionary called rxns just like the species before.\n",
"\n",
"More information on the Arrhenius reaction can be found [here](https://mechanismconfiguration.readthedocs.io/en/latest/v1/reactions/arrhenius.html).\n",
"\n",
"**Note:** MusicBox allows for users to experiment with an array of reaction types.\n",
"\n",
"Go [here](https://mechanismconfiguration.readthedocs.io/en/latest/v1/reactions/index.html) to view a list of supported reactions and their parameters."
]
},
{
"cell_type": "markdown",
"id": "f465f101",
"metadata": {},
"source": [
"### 4c. Defining Mechanisms\n",
"\n",
"A mechanism represents a set of species with their respective phases and reactions.\n",
"\n",
"For extended documentation about the Mechanism class, go [here](https://ncar-musica.readthedocs.io/en/latest/user_guide/python/chemistry/index.html#mechanisms).\n",
"\n",
"To create a mechanism in MusicBox:"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "25da888c",
"metadata": {},
"outputs": [],
"source": [
"# Create the mechanism that is defined by the species, phases, and reactions\n",
"mechanism = mc.Mechanism(name=\"tutorial_mechanism\", species=list(species.values()), phases=[gas], reactions=list(rxns.values()))"
]
},
{
"cell_type": "markdown",
"id": "b4ee16f5",
"metadata": {},
"source": [
"This code block builds upon the previous two functions, using the previously-created species, phases, and reactions as arguments.\n",
"\n",
"It simply creates a mechanism variable that represents an instance of the Mechanism class.\n",
"\n",
"The mechanism is first given a name, then the species, phase, and reactions are passed into their respective arguments."
]
},
{
"cell_type": "markdown",
"id": "6cbf0090",
"metadata": {},
"source": [
"## 5. Creating a Box Model\n",
"\n",
"Box models allow you to solve your previously-created mechanism under conditions that can change the reactions' rates over time.\n",
"\n",
"Each instance of the MusicBox class acts as an independent box model.\n",
"\n",
"You can also define the length of the simulations and the time steps.\n",
"\n",
"To initialize a new box model:"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "ae8134a6",
"metadata": {},
"outputs": [],
"source": [
"# Create the box model that contains the mechanism\n",
"box_model = MusicBox()\n",
"box_model.load_mechanism(mechanism)"
]
},
{
"cell_type": "markdown",
"id": "e1ecacc8",
"metadata": {},
"source": [
"This code block is straightforward, simply creating an instance of the MusicBox class and then loading the mechanism as an argument for the box model."
]
},
{
"cell_type": "markdown",
"id": "aa814af4",
"metadata": {},
"source": [
"### 5a. Adding Initial Conditions to Your Box Model\n",
"\n",
"The initial conditions of the model define the environment the mechanism takes place in at the start of the simulation.\n",
"\n",
"Some conditions that are recommended to define for your system include:\n",
"* the temperature, measured in Kelvin (K),\n",
"* the pressure, measured in Pascals (Pa), and\n",
"* the concentration of each of the species, measured in mol/m³.\n",
"\n",
"To set the initial conditions of your box model, use the `set_condition()` method with `time=0`:"
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "3e83223d",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
""
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# Set the conditions of the box model at time = 0 s\n",
"box_model.set_condition(\n",
" time=0,\n",
" temperature=298.15, # Units: Kelvin (K)\n",
" pressure=101325.0, # Units: Pascals (Pa)\n",
" concentrations={ # Units: mol/m^3\n",
" \"X\": 3.75,\n",
" \"Y\": 5.0,\n",
" \"Z\": 2.5,\n",
" }\n",
")"
]
},
{
"cell_type": "markdown",
"id": "021d5e5d",
"metadata": {},
"source": [
"You provide a time value (0 for initial conditions), along with temperature, pressure, and each of the species' concentrations as keyword arguments. Air density is optional (by default it's calculated using the Ideal Gas Law)."
]
},
{
"cell_type": "markdown",
"id": "c49c4078",
"metadata": {},
"source": [
"### 5b. Adding Evolving Conditions to Your Box Model\n",
"\n",
"Evolving conditions allow you to change the environment of the mechanism at specific time points.\n",
"\n",
"These changes can include species concentration, temperature, pressure, etc.\n",
"\n",
"To create evolving conditions for your box model, use the same `set_condition()` method with a different time value:"
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "b157a3e8",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
""
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# Set the box model conditions at the defined time\n",
"box_model.set_condition(\n",
" time=100.0, # Units: Seconds (s)\n",
" temperature=275.0, # Units: Kelvin (K)\n",
" pressure=100100.0 # Units: Pascals (Pa)\n",
")"
]
},
{
"cell_type": "markdown",
"id": "9c7b120f",
"metadata": {},
"source": [
"This code block is similar to setting the initial conditions, but uses a different time value.\n",
"\n",
"The `set_condition()` method is called again with `time=100.0` to specify that these conditions (temperature and pressure changes) should take effect at 100 seconds into the simulation.\n",
"\n",
"You can call `set_condition()` multiple times with different time values to create a sequence of environmental changes throughout your simulation."
]
},
{
"cell_type": "markdown",
"id": "e4e87b99",
"metadata": {},
"source": [
"### 5c. Additional Box Model Configuration\n",
"\n",
"Box models contain some additional configuration options that need to be defined.\n",
"\n",
"These include:\n",
"* the simulation length,\n",
"* the chemistry step time, and\n",
"* the output step time.\n",
"\n",
"To set these configurations for your box model:"
]
},
{
"cell_type": "code",
"execution_count": 8,
"id": "6e00fa9a",
"metadata": {},
"outputs": [],
"source": [
"# Set the additional configuration options for the box model\n",
"box_model.box_model_options.simulation_length = 200 # Units: Seconds (s)\n",
"box_model.box_model_options.chem_step_time = 1 # Units: Seconds (s)\n",
"box_model.box_model_options.output_step_time = 20 # Units: Seconds (s)"
]
},
{
"cell_type": "markdown",
"id": "f5164733",
"metadata": {},
"source": [
"This code block sets some of the attributes of the box model's options, including:\n",
"\n",
"* **simulation_length:** the total duration of the simulation (in seconds),\n",
"* **chem_step_time:** the time interval between each chemistry calculation (in seconds), and\n",
"* **output_step_time:** the time interval between each output data point (in seconds).\n",
"\n",
"All three of these use seconds as their unit."
]
},
{
"cell_type": "markdown",
"id": "d20aa95a",
"metadata": {},
"source": [
"## 6. Solving Your Box Model\n",
"\n",
"Now, you are able to run and solve your newly-created box model.\n",
"\n",
"To solve your box model, simply call its `solve()` function:"
]
},
{
"cell_type": "code",
"execution_count": 9,
"id": "7e09be6b",
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
" "
]
}
],
"source": [
"df = box_model.solve()"
]
},
{
"cell_type": "markdown",
"id": "5846cc70",
"metadata": {},
"source": [
"The `solve()` method returns a pandas DataFrame containing the simulation results."
]
},
{
"cell_type": "markdown",
"id": "4652b4ee",
"metadata": {},
"source": [
"## 7. View Outputs and Visualizations\n",
"The DataFrame includes the following columns:\n",
"\n",
"* **time.s** - Simulation time in seconds\n",
"* **ENV.temperature.K** - Temperature at each time step in Kelvin\n",
"* **ENV.pressure.Pa** - Pressure at each time step in Pascals\n",
"* **ENV.air number density.mol m-3** - Air density in mol/m³\n",
"* **CONC.X.mol m-3**, **CONC.Y.mol m-3**, **CONC.Z.mol m-3** - Species concentrations in mol/m³ for each species in your mechanism\n",
"\n",
"This structured format makes it easy to analyze, visualize, and export your simulation results.\n",
"\n",
"To view your solved model's data and a basic visualization of it:"
]
},
{
"cell_type": "code",
"execution_count": 10,
"id": "782b1107",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"
\n",
" \n",
" \n",
" time.s \n",
" ENV.temperature.K \n",
" ENV.pressure.Pa \n",
" ENV.air number density.mol m-3 \n",
" CONC.X.mol m-3 \n",
" CONC.Y.mol m-3 \n",
" CONC.Z.mol m-3 \n",
" \n",
" \n",
" \n",
" \n",
" count \n",
" 11.000000 \n",
" 11.000000 \n",
" 11.000000 \n",
" 11.000000 \n",
" 11.000000 \n",
" 11.000000 \n",
" 11.000000 \n",
" \n",
" \n",
" mean \n",
" 100.000000 \n",
" 287.627273 \n",
" 100768.181818 \n",
" 42.194541 \n",
" 2.439584 \n",
" 4.194061 \n",
" 4.616355 \n",
" \n",
" \n",
" std \n",
" 66.332496 \n",
" 12.089693 \n",
" 639.735386 \n",
" 1.517135 \n",
" 0.762650 \n",
" 0.572226 \n",
" 1.329958 \n",
" \n",
" \n",
" min \n",
" 0.000000 \n",
" 275.000000 \n",
" 100100.000000 \n",
" 40.874045 \n",
" 1.446236 \n",
" 3.306276 \n",
" 2.500000 \n",
" \n",
" \n",
" 25% \n",
" 50.000000 \n",
" 275.000000 \n",
" 100100.000000 \n",
" 40.874045 \n",
" 1.840420 \n",
" 3.761719 \n",
" 3.640977 \n",
" \n",
" \n",
" 50% \n",
" 100.000000 \n",
" 298.150000 \n",
" 101325.000000 \n",
" 40.874045 \n",
" 2.336660 \n",
" 4.220865 \n",
" 4.692475 \n",
" \n",
" \n",
" 75% \n",
" 150.000000 \n",
" 298.150000 \n",
" 101325.000000 \n",
" 43.779137 \n",
" 2.963461 \n",
" 4.645562 \n",
" 5.647861 \n",
" \n",
" \n",
" max \n",
" 200.000000 \n",
" 298.150000 \n",
" 101325.000000 \n",
" 43.779137 \n",
" 3.750000 \n",
" 5.000000 \n",
" 6.497488 \n",
" \n",
" \n",
"
\n",
"
\n",
"\n",
"
\n",
" \n",
" \n",
" time.s \n",
" ENV.temperature.K \n",
" ENV.pressure.Pa \n",
" ENV.air number density.mol m-3 \n",
" CONC.X.mol m-3 \n",
" CONC.Y.mol m-3 \n",
" CONC.Z.mol m-3 \n",
" \n",
" \n",
" \n",
" \n",
" 0 \n",
" 0.0 \n",
" 298.15 \n",
" 101325.0 \n",
" 40.874045 \n",
" 3.750000 \n",
" 5.000000 \n",
" 2.500000 \n",
" \n",
" \n",
" 1 \n",
" 20.0 \n",
" 298.15 \n",
" 101325.0 \n",
" 40.874045 \n",
" 3.411490 \n",
" 4.871403 \n",
" 2.967107 \n",
" \n",
" \n",
" 2 \n",
" 40.0 \n",
" 298.15 \n",
" 101325.0 \n",
" 40.874045 \n",
" 3.103538 \n",
" 4.725280 \n",
" 3.421182 \n",
" \n",
" \n",
" 3 \n",
" 60.0 \n",
" 298.15 \n",
" 101325.0 \n",
" 40.874045 \n",
" 2.823383 \n",
" 4.565844 \n",
" 3.860773 \n",
" \n",
" \n",
" 4 \n",
" 80.0 \n",
" 298.15 \n",
" 101325.0 \n",
" 40.874045 \n",
" 2.568519 \n",
" 4.396687 \n",
" 4.284794 \n",
" \n",
" \n",
" 5 \n",
" 100.0 \n",
" 298.15 \n",
" 101325.0 \n",
" 40.874045 \n",
" 2.336660 \n",
" 4.220865 \n",
" 4.692475 \n",
" \n",
" \n",
" 6 \n",
" 120.0 \n",
" 275.00 \n",
" 100100.0 \n",
" 43.779137 \n",
" 2.122874 \n",
" 4.038383 \n",
" 5.088743 \n",
" \n",
" \n",
" 7 \n",
" 140.0 \n",
" 275.00 \n",
" 100100.0 \n",
" 43.779137 \n",
" 1.928648 \n",
" 3.853960 \n",
" 5.467392 \n",
" \n",
" \n",
" 8 \n",
" 160.0 \n",
" 275.00 \n",
" 100100.0 \n",
" 43.779137 \n",
" 1.752192 \n",
" 3.669479 \n",
" 5.828329 \n",
" \n",
" \n",
" 9 \n",
" 180.0 \n",
" 275.00 \n",
" 100100.0 \n",
" 43.779137 \n",
" 1.591880 \n",
" 3.486494 \n",
" 6.171626 \n",
" \n",
" \n",
" 10 \n",
" 200.0 \n",
" 275.00 \n",
" 100100.0 \n",
" 43.779137 \n",
" 1.446236 \n",
" 3.306276 \n",
" 6.497488 \n",
" \n",
" \n",
"
\n",
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"display(df.describe())\n",
"display(df)\n",
"df.plot(x='time.s', y=['CONC.X.mol m-3', 'CONC.Y.mol m-3', 'CONC.Z.mol m-3'], title='Concentration over time', ylabel='Concentration (mol m-3)', xlabel='Time (s)')\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"id": "26d32598",
"metadata": {},
"source": [
"The first `display()` call shows statistical summary information about the DataFrame (count, mean, standard deviation, min/max values).\n",
"\n",
"The second `display()` shows the full DataFrame with all time steps and their corresponding values.\n",
"\n",
"The `plot()` function from pandas creates a line plot visualization:\n",
"* **x='time.s'** - Sets time as the x-axis\n",
"* **y=[...]** - Lists the species concentrations to plot on the y-axis\n",
"* **title, xlabel, ylabel** - Add labels to make the plot readable\n",
"\n",
"The `plt.show()` displays the plot in the notebook.\n",
"\n",
"**Note:** If you are running this code in a Jupyter notebook, use `display()` as shown above. If you're running this as a Python script in a terminal, replace `display()` with `print()`."
]
}
],
"metadata": {
"kernelspec": {
"display_name": "musica",
"language": "python",
"name": "musica"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.14.2"
}
},
"nbformat": 4,
"nbformat_minor": 5
}